docs: ML-KEM quick start, Kyber migration guide, version 2.0.0 (WP-7) - #39

This is WP-7 (#15). It changes docs and the version only: no Rust or Python behavior changes, nothing removed or renamed, no tests touched.

Three commits. The first adds docs/migration.md, the path the KyberDeprecationWarning already links to on main. It says that Kyber (round 3) and ML-KEM are not interoperable, that both sides have to switch, that the shared secret changes, that key and ciphertext sizes are identical so bytes cannot tell the families apart, that the ML-KEM seed is 64 bytes (d || z, shown as .seed only for seeded keypairs, and secret), and that ML-KEM methods refuse Kyber objects with AlgorithmMismatchError. It also explains why the warning is usually invisible (DeprecationWarning is shown by default only from main) and how to turn it on. The second switches the README quick start and API usage, docs/api.md and docs/index.md to ML_KEM_768 and documents the Kyber classes as deprecated, without examples. The third bumps the version to 2.0.0 in Cargo.toml and pyproject.toml (plus the Documentation link and the package description in pyproject.toml), commits Cargo.lock, and turns the Unreleased changelog lines into a 2.0.0 entry. The entry says the release is planned and not tagged.

The only examples left that use Kyber are the two in docs/migration.md. The README performance table still reports the Kyber benchmark numbers and now says so; I did not rerun the benchmark for ML-KEM. I also left the tests, vector generators and benchmark script alone, as the handoff asked.

README security wording: it claims no audit and no constant-time guarantee. It says the ML-KEM code is checked against ACVP, CCTV, Wycheproof and a dev-only differential test, and that the side-channel review planned for 2.0 is not finished.

Verified (how): every python block in README.md and docs/migration.md was executed against a fresh maturin develop build in a new venv, and the output matched what the text says (a Kyber keypair passed to ML_KEM_768.encapsulate raises AlgorithmMismatchError; passing raw Kyber public-key bytes does not raise and gives a secret the Kyber holder does not have; the same 64-byte seed gives different public keys in Kyber768 and ML_KEM_768). I first wrote that -W error::pykyber.KyberDeprecationWarning turns the warning into an error; running it showed it does not, so the page uses warnings.simplefilter instead, which I ran. cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo +stable clippy were clean. git rebase --exec scripts/check.sh origin/dev-v2 passed on all three commits (fmt, clippy, cargo test --locked, maturin develop, 2464 pytest tests each).

Believed, not verified: that the wording about how ML-KEM differs from round 3 (k byte in key generation, no message pre-hash, no ciphertext hash in the KDF) matches the standard; I took it from PLAN-2.0.md section 2 and the code comments rather than rereading FIPS 203 appendix C. I did not build wheels or check the rendered markdown on GitHub. The migration link in the warning will 404 until dev-v2 is merged into main, as the handoff expected.

Out of scope: the Makefile benchmark and performance-tests still measure only Kyber. PLAN-2.0 section 5 items (rc on TestPyPI, tag, the Documentation link moving off a tag once main is the default) are the maintainer's.

Checklist

• Spec sections cited in code for new crypto logic (n.a., no code)
• Legacy golden vectors pass unchanged (tests untouched; ran in scripts/check.sh)
• No secret-dependent branches, divisions, or indexing (asm checked: n.a.)
• Secret intermediates zeroized on all paths (n.a.)
• Inputs validated before secret-dependent work (n.a.)
• No new runtime deps; no unsafe; no panics on untrusted input
• No magic numbers (n.a.)
• Tests added (n.a., docs only); fmt/clippy/test/pytest green on every commit (git rebase --exec)
• Review fixes folded into the commits they fix; rebased on current dev-v2
• CHANGELOG updated
• Sources checked: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf - 2026-10-30 - section 8 (Parameter Sets): "NIST recommends using ML-KEM-768 as the default parameter set"; no change from PLAN-2.0.md

Generated with Claude Code